<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
		<meta http-equiv="content-type" content="text/html; charset=utf-8" />
		<meta name="generator" content="JsDoc Toolkit" />
		
		<title>JsDoc Reference - pv.Nest</title>

		<style type="text/css">
			/* default.css */
body
{
	font: 12px "Lucida Grande", Tahoma, Arial, Helvetica, sans-serif;
	width: 800px;
}

.header
{
	clear: both;
	background-color: #ccc;
	padding: 8px;
}

h1
{
	font-size: 150%;
	font-weight: bold;
	padding: 0;
	margin: 1em 0 0 .3em;
}

hr
{
	border: none 0;
	border-top: 1px solid #7F8FB1;
	height: 1px;
}

pre.code
{
	display: block;
	padding: 8px;
	border: 1px dashed #ccc;
}

#index
{
	margin-top: 24px;
	float: left;
	width: 160px;
	position: absolute;
	left: 8px;
	background-color: #F3F3F3;
	padding: 8px;
}

#content
{
	margin-left: 190px;
	width: 600px;
}

.classList
{
	list-style-type: none;
	padding: 0;
	margin: 0 0 0 8px;
	font-family: arial, sans-serif;
	font-size: 1em;
	overflow: auto;
}

.classList li
{
	padding: 0;
	margin: 0 0 8px 0;
}

.summaryTable { width: 100%; }

h1.classTitle
{
	font-size:170%;
	line-height:130%;
}

h2 { font-size: 110%; }
caption, div.sectionTitle
{
	background-color: #7F8FB1;
	color: #fff;
	font-size:130%;
	text-align: left;
	padding: 2px 6px 2px 6px;
	border: 1px #7F8FB1 solid;
}

div.sectionTitle { margin-bottom: 8px; }
.summaryTable thead { display: none; }

.summaryTable td
{
	vertical-align: top;
	padding: 4px;
	border-bottom: 1px #7F8FB1 solid;
	border-right: 1px #7F8FB1 solid;
}

/*col#summaryAttributes {}*/
.summaryTable td.attributes
{
	border-left: 1px #7F8FB1 solid;
	width: 140px;
	text-align: right;
}

td.attributes, .fixedFont
{
	line-height: 15px;
	color: #002EBE;
	font-family: "Courier New",Courier,monospace;
	font-size: 13px;
}

.summaryTable td.nameDescription
{
	text-align: left;
	font-size: 13px;
	line-height: 15px;
}

.summaryTable td.nameDescription, .description
{
	line-height: 15px;
	padding: 4px;
	padding-left: 4px;
}

pre
{
	border-left: solid 10px #ddd;
	padding-left: 1.5em;
}

.summaryTable { margin-bottom: 8px; }

ul.inheritsList
{
	list-style: square;
	margin-left: 20px;
	padding-left: 0;
}

.detailList {
	margin-left: 20px; 
	line-height: 15px;
}
.detailList dt { margin-left: 20px; }

.detailList .heading
{
	font-weight: bold;
	padding-bottom: 6px;
	margin-left: 0;
}

.light, td.attributes, .light a:link, .light a:visited
{
	color: #777;
	font-style: italic;
}

.fineprint
{
	text-align: right;
	font-size: 10px;
}

		</style>
	</head>

	<body>
<!-- ============================== header ================================= -->	
		<!-- begin static/header.html -->
		<div id="header">
</div>
		<!-- end static/header.html -->

<!-- ============================== classes index ============================ -->
		<div id="index">
			<!-- begin publish.classesIndex -->
			<div align="center"><a href="../index.html">Class Index</a>
| <a href="../files.html">File Index</a></div>
<hr />
<h2>Classes</h2>
<ul class="classList">
	
	<li><i><a href="../symbols/_global_.html">_global_</a></i></li>
	
	<li><a href="../symbols/Array.html">Array</a></li>
	
	<li><a href="../symbols/Date.html">Date</a></li>
	
	<li><a href="../symbols/pv.html">pv</a></li>
	
	<li><a href="../symbols/pv.Anchor.html">pv.Anchor</a></li>
	
	<li><a href="../symbols/pv.Area.html">pv.Area</a></li>
	
	<li><a href="../symbols/pv.Bar.html">pv.Bar</a></li>
	
	<li><a href="../symbols/pv.Color.html">pv.Color</a></li>
	
	<li><a href="../symbols/pv.Color.Hsl.html">pv.Color.Hsl</a></li>
	
	<li><a href="../symbols/pv.Color.Rgb.html">pv.Color.Rgb</a></li>
	
	<li><a href="../symbols/pv.Colors.html">pv.Colors</a></li>
	
	<li><a href="../symbols/pv.Dot.html">pv.Dot</a></li>
	
	<li><a href="../symbols/pv.Flatten.html">pv.Flatten</a></li>
	
	<li><a href="../symbols/pv.Image.html">pv.Image</a></li>
	
	<li><a href="../symbols/pv.Label.html">pv.Label</a></li>
	
	<li><a href="../symbols/pv.Layout.grid.html">pv.Layout.grid</a></li>
	
	<li><a href="../symbols/pv.Layout.icicle.html">pv.Layout.icicle</a></li>
	
	<li><a href="../symbols/pv.Layout.stack.html">pv.Layout.stack</a></li>
	
	<li><a href="../symbols/pv.Layout.sunburst.html">pv.Layout.sunburst</a></li>
	
	<li><a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a></li>
	
	<li><a href="../symbols/pv.Line.html">pv.Line</a></li>
	
	<li><a href="../symbols/pv.Mark.html">pv.Mark</a></li>
	
	<li><a href="../symbols/pv.Nest.html">pv.Nest</a></li>
	
	<li><a href="../symbols/pv.ns.html">pv.ns</a></li>
	
	<li><a href="../symbols/pv.Panel.html">pv.Panel</a></li>
	
	<li><a href="../symbols/pv.Rule.html">pv.Rule</a></li>
	
	<li><a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a></li>
	
	<li><a href="../symbols/pv.Scale.log.html">pv.Scale.log</a></li>
	
	<li><a href="../symbols/pv.Scale.ordinal.html">pv.Scale.ordinal</a></li>
	
	<li><a href="../symbols/pv.Tree.html">pv.Tree</a></li>
	
	<li><a href="../symbols/pv.Vector.html">pv.Vector</a></li>
	
	<li><a href="../symbols/pv.version.html">pv.version</a></li>
	
	<li><a href="../symbols/pv.Wedge.html">pv.Wedge</a></li>
	
</ul>
<hr />
			<!-- end publish.classesIndex -->
		</div>
		
		<div id="content">
<!-- ============================== class title ============================ -->
			<h1 class="classTitle">
				
				Class pv.Nest
			</h1>

<!-- ============================== class summary ========================== -->			
			<p class="description">
				
			
				Represents a Nest operator for the specified array. Nesting
allows elements in an array to be grouped into a hierarchical tree
structure. The levels in the tree are specified by <i>key</i> functions. The
leaf nodes of the tree can be sorted by value, while the internal nodes can
be sorted by key. Finally, the tree can be returned either has a
multidimensional array via <a href="#entries">#entries</a>, or as a hierarchical map via
<a href="#map">#map</a>. The <a href="#rollup">#rollup</a> routine similarly returns a map, collapsing
the elements in each leaf node using a summary function.

<p>For example, consider the following tabular data structure of Barley
yields, from various sites in Minnesota during 1931-2:

<pre>{ yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm" },
{ yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca" },
{ yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris" }, ...</pre>

To facilitate visualization, it may be useful to nest the elements first by
year, and then by variety, as follows:

<pre>var nest = pv.nest(yields)
    .key(function(d) d.year)
    .key(function(d) d.variety)
    .entries();</pre>

This returns a nested array. Each element of the outer array is a key-values
pair, listing the values for each distinct key:

<pre>{ key: 1931, values: [
  { key: "Manchuria", values: [
      { yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm" },
      { yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca" },
      { yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris" },
      ...
    ] },
  { key: "Glabron", values: [
      { yield: 43.07, variety: "Glabron", year: 1931, site: "University Farm" },
      { yield: 55.20, variety: "Glabron", year: 1931, site: "Waseca" },
      ...
    ] },
  ] },
{ key: 1932, values: ... }</pre>

Further details, including sorting and rollup, is provided below on the
corresponding methods.
				
				
					<br /><i>Defined in: </i> <a href="../symbols/src/data_Nest.js.html">Nest.js</a>.
				
			</p>

<!-- ============================== constructor summary ==================== -->			
			
			<table class="summaryTable" cellspacing="0" summary="A summary of the constructor documented in the class pv.Nest.">
				<caption>Class Summary</caption>
				<thead>
					<tr>
						<th scope="col">Constructor Attributes</th>
						<th scope="col">Constructor Name and Description</th>
					</tr>
				</thead>
				<tbody>
					<tr>
						<td class="attributes">&nbsp;</td>
						<td class="nameDescription" >
							<div class="fixedFont">
								<b><a href="../symbols/pv.Nest.html#constructor">pv.Nest</a></b>(array)
							</div>
							<div class="description">Constructs a nest operator for the specified array.</div>
						</td>
					</tr>
				</tbody>
			</table>
			

<!-- ============================== properties summary ===================== -->
			

<!-- ============================== methods summary ======================== -->
			
				
				
				<table class="summaryTable" cellspacing="0" summary="A summary of the methods documented in the class pv.Nest.">
					<caption>Method Summary</caption>
					<thead>
						<tr>
							<th scope="col">Method Attributes</th>
							<th scope="col">Method Name and Description</th>
						</tr>
					</thead>
					<tbody>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Nest.html#entries">entries</a></b>()
								</div>
								<div class="description">Returns a hierarchical nested array.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Nest.html#key">key</a></b>(key)
								</div>
								<div class="description">Nests using the specified key function.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Nest.html#map">map</a></b>()
								</div>
								<div class="description">Returns a hierarchical map of values.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Nest.html#rollup">rollup</a></b>(f)
								</div>
								<div class="description">Returns a rollup map.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Nest.html#sortKeys">sortKeys</a></b>(order)
								</div>
								<div class="description">Sorts the previously-added keys.</div>
							</td>
						</tr>
					
						<tr>
							<td class="attributes">&nbsp;</td>
							<td class="nameDescription">
								<div class="fixedFont"><b><a href="../symbols/pv.Nest.html#sortValues">sortValues</a></b>(order)
								</div>
								<div class="description">Sorts the leaf values.</div>
							</td>
						</tr>
					
					</tbody>
				</table>
				
				
				
			
<!-- ============================== events summary ======================== -->
			

<!-- ============================== constructor details ==================== -->		
			
			<div class="details"><a name="constructor"> </a>
				<div class="sectionTitle">
					Class Detail
				</div>
				
				<div class="fixedFont">
						<b>pv.Nest</b>(array)
				</div>
				
				<div class="description">
					Constructs a nest operator for the specified array. This constructor should
not be invoked directly; use <a href="../symbols/pv.html#.nest">pv.nest</a> instead.
					
				</div>
				
				
				
				
					
						<dl class="detailList">
						<dt class="heading">Parameters:</dt>
						
							<dt>
								<span class="light fixedFont">{array}</span>  <b>array</b>
								
							</dt>
								<dd>an array of elements to nest.</dd>
						
						</dl>
					
					
					
					
					
					
					

			</div>
			

<!-- ============================== field details ========================== -->		
			

<!-- ============================== method details ========================= -->		
			
				<div class="sectionTitle">
					Method Detail
				</div>
				
					<a name="entries"> </a>
					<div class="fixedFont">
					
					
					<b>entries</b>()
					
					</div>
					<div class="description">
						Returns a hierarchical nested array. This method is similar to
<a href="../symbols/pv.html#.entries">pv.entries</a>, but works recursively on the entire hierarchy. Rather
than returning a map like <a href="#map">#map</a>, this method returns a nested
array. Each element of the array has a <tt>key</tt> and <tt>values</tt>
field. For leaf nodes, the <tt>values</tt> array will be a subset of the
underlying elements array; for non-leaf nodes, the <tt>values</tt> array will
contain more key-values pairs.

<p>For an example usage, see the Nest constructor.
						
						
					</div>
					
					
					
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd>a hierarchical nested array.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="key"> </a>
					<div class="fixedFont">
					
					<span class="light">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span>
					<b>key</b>(key)
					
					</div>
					<div class="description">
						Nests using the specified key function. Multiple keys may be added to the
nest; the array elements will be nested in the order keys are specified.
						
						
					</div>
					
					
					
						
							<dl class="detailList">
							<dt class="heading">Parameters:</dt>
							
								<dt>
									<span class="light fixedFont">{function}</span> <b>key</b>
									
								</dt>
								<dd>a key function; must return a string or suitable map
key.</dd>
							
							</dl>
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span> this.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="map"> </a>
					<div class="fixedFont">
					
					
					<b>map</b>()
					
					</div>
					<div class="description">
						Returns a hierarchical map of values. Each key adds one level to the
hierarchy. With only a single key, the returned map will have a key for each
distinct value of the key function; the correspond value with be an array of
elements with that key value. If a second key is added, this will be a nested
map. For example:

<pre>pv.nest(yields)
    .key(function(d) d.variety)
    .key(function(d) d.site)
    .map()</pre>

returns a map <tt>m</tt> such that <tt>m[variety][site]</tt> is an array, a subset of
<tt>yields</tt>, with each element having the given variety and site.
						
						
					</div>
					
					
					
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd>a hierarchical map of values.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="rollup"> </a>
					<div class="fixedFont">
					
					
					<b>rollup</b>(f)
					
					</div>
					<div class="description">
						Returns a rollup map. The behavior of this method is the same as
<a href="#map">#map</a>, except that the leaf values are replaced with the return value
of the specified rollup function <tt>f</tt>. For example,

<pre>pv.nest(yields)
     .key(function(d) d.site)
     .rollup(function(v) pv.median(v, function(d) d.yield))</pre>

first groups yield data by site, and then returns a map from site to median
yield for the given site.
						
						
					</div>
					
					
					
						
							<dl class="detailList">
							<dt class="heading">Parameters:</dt>
							
								<dt>
									<span class="light fixedFont">{function}</span> <b>f</b>
									
								</dt>
								<dd>a rollup function.</dd>
							
							</dl>
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd>a hierarchical map, with the leaf values computed by <tt>f</tt>.</dd>
							
							</dl>
						
						
						
							<dl class="detailList">
							<dt class="heading">See:</dt>
							
								<dd><a href="#map">#map</a></dd>
							
							</dl>
						

					<hr />
				
					<a name="sortKeys"> </a>
					<div class="fixedFont">
					
					<span class="light">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span>
					<b>sortKeys</b>(order)
					
					</div>
					<div class="description">
						Sorts the previously-added keys. The natural sort order is used by default
(see <a href="../symbols/pv.html#.naturalOrder">pv.naturalOrder</a>); if an alternative order is desired,
<tt>order</tt> should be a comparator function. If this method is not called
(i.e., keys are <i>unsorted</i>), keys will appear in the order they appear
in the underlying elements array. For example,

<pre>pv.nest(yields)
    .key(function(d) d.year)
    .key(function(d) d.variety)
    .sortKeys()
    .entries()</pre>

groups yield data by year, then variety, and sorts the variety groups
lexicographically (since the variety attribute is a string).

<p>Key sort order is only used in conjunction with <a href="#entries">#entries</a>, which
returns an array of key-values pairs. If the nest is used to construct a
<a href="#map">#map</a> instead, keys are unsorted.
						
						
					</div>
					
					
					
						
							<dl class="detailList">
							<dt class="heading">Parameters:</dt>
							
								<dt>
									<span class="light fixedFont">{function}</span> <b>order</b>
									<i>Optional</i>
								</dt>
								<dd>an optional comparator function.</dd>
							
							</dl>
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span> this.</dd>
							
							</dl>
						
						
						

					<hr />
				
					<a name="sortValues"> </a>
					<div class="fixedFont">
					
					<span class="light">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span>
					<b>sortValues</b>(order)
					
					</div>
					<div class="description">
						Sorts the leaf values. The natural sort order is used by default (see
<a href="../symbols/pv.html#.naturalOrder">pv.naturalOrder</a>); if an alternative order is desired, <tt>order</tt>
should be a comparator function. If this method is not called (i.e., values
are <i>unsorted</i>), values will appear in the order they appear in the
underlying elements array. For example,

<pre>pv.nest(yields)
    .key(function(d) d.year)
    .key(function(d) d.variety)
    .sortValues(function(a, b) a.yield - b.yield)
    .entries()</pre>

groups yield data by year, then variety, and sorts the values for each
variety group by yield.

<p>Value sort order, unlike keys, applies to both <a href="#entries">#entries</a> and
<a href="#map">#map</a>. It has no effect on <a href="#rollup">#rollup</a>.
						
						
					</div>
					
					
					
						
							<dl class="detailList">
							<dt class="heading">Parameters:</dt>
							
								<dt>
									<span class="light fixedFont">{function}</span> <b>order</b>
									<i>Optional</i>
								</dt>
								<dd>an optional comparator function.</dd>
							
							</dl>
						
						
						
						
						
							<dl class="detailList">
							<dt class="heading">Returns:</dt>
							
								<dd><span class="light fixedFont">{<a href="../symbols/pv.Nest.html">pv.Nest</a>}</span> this.</dd>
							
							</dl>
						
						
						

					
				
			
			
<!-- ============================== event details ========================= -->		
			
			
			<hr />
		</div>

		
<!-- ============================== footer ================================= -->
		<div class="fineprint" style="clear:both">
			
			Documentation generated by <a href="http://code.google.com/p/jsdoc-toolkit/" target="_blank">JsDoc Toolkit</a> 2.3.0 on Tue Oct 06 2009 09:59:02 GMT-0700 (PDT)
		</div>
	</body>
</html>
